All the parts in a document share a common application heap. Unfortunately, like all application heaps (circa System 7.X) this is fixed size and cannot grow. Since every document has its own heap, we want to keep these as small as possible; the default size in OpenDoc 1.0 is 384k. Much of this space is occupied by some stuff the system loads there that we can't do anything about — things like the stack and CFM globals.
We've provided a mechanism for the user to increase the document heap space if it runs out; there's a size control in the Document Info dialog. However, the heap size can't change until the document is closed and re-opened, so this is not very convenient for the user.
This implies that application heap space is a scarce commodity. It is very bad etiquette for your part editor to use application heap space unnecessarily. Whenever possible, you should allocate space in Temporary Memory.
These limitations are annoying, and stem from the existing Macintosh memory model. They will go away completely in Copland (System 8). Until then you'll have to be careful.
Bad Things To Do:
All of OpenDoc's memory allocation functions — MMAllocate, ODNewPtr, ODNewHandle, even the global 'operator new' defined by ODNew.cpp — allocate in temp mem. The problem comes in when you do one of the following Bad Things:
• Call NewHandle. Don't do this. Call NewTempHandle or ODNewHandle instead.
• Call 'malloc'. The ANSI libraries provided with your development environment get the memory for this by allocating large blocks in the application heap (which are never freed until the process quits.) You should use MMAllocate (in MemMgr.h) instead. Or you could use the SOM routine somMalloc, which does the same thing. If your code uses exception handling as per the Except utility, it's more convenient to use ODNewPtr (from ODMemory) which throws an exception when it runs out of memory.
• Call NewRgn. Call ODNewRgn (in ODMemory.h) instead; this allocates the region in temporary memory. If you don't want to use ODMemory, see the definition of ODNewRgn in ODMemory.cpp and copy and paste it into your code.
• Load too many resources (GetResource, etc.) In UseRsrcM.h are a couple of routines that you can use to load resources directly into temporary memory. You could also load the resource, copy the data into a block in temp mem, and immediately release the resource. However, there are cases where you have to load a resource normally and have it remain a resource. Just try to keep the resource small and don't leave it in memory too long.
• Create GWorlds. Please use the temp-mem flag with NewGWorld to allocate the frame buffer in temp mem.
• Call other Toolbox managers (which shall remain nameless) that allocate handles and don't give you control over what heap they're created in. This can be a real problem. You could be careful to preflight, and if there's not enough room ask the user to increase the document heap size (via the Document Info command) and close and re-open the document. Of course, this sucks. You could also create your own heap in temp mem by calling NewTempHandle, locking it down, and creating a zone in the block. You can then switch to that heap before calling the routines that allocate in the current heap. Make sure to dispose this heap when you're through with it.
Preflight!
Before doing something that will allocate memory in the application heap — especially something where the Toolbox implicitly allocates the memory, such as displaying a dialog — check whether there's enough space. You can directly call the OpenDoc Memory Manager (<MemMgr.h>) routine MMSystemFreeSpace, passing kMMAppMemory as the location, or you can use the utility (<ODMemory.h>) functions ODHaveFreeSpace or ODRequireFreeSpace (passing kODTrue for the final appHeap parameter) or ODCheckAppHeapSpace, which are in the utility ODMemory.
References:
Inside Macintosh: Memory describes temporary memory and how to use it.
Inside Macintosh: Imaging With QuickDraw describes GWorlds and how to put them in temp mem.
The OpenDoc tech note “Memory Manager” describes the OpenDoc memory manager.
The OpenDoc utilities MemMgr, ODMemory and UseRsrcM.
